Mac Format 1996 April/MacFormat CD Edition MF36 (April 1996).iso/Shareware City/Developers/Tools Plus - GUI⁄Event libs/Tools Plus 2.6.1a Evaluat'n Kit/Tools Plus 2.6.1a/User Manual/09-Editing Fields (1 of 2)

INI File | 1994-09-17 | 27KB | 298 lines

[Display using Monaco 9]


9  Editing Fields
`````````````````

  Editing fields are supported by Tools Plus windows with some notable enhancements over the Macintosh’s standard TextEdit fields.  Editing fields (or simply “fields”) are created on the current window by the NewField procedure.  Each field is referenced by a unique field number that can be from 1 to 255.  This number is specified when the field is created, and refers to the specific field until that field is deleted.  Note that the field number is related to its associated window.  This means that two different windows can each have a field numbered “1” without interfering with each other.  Whenever any field event occurs, such as the user clicking on a field, the PollSystem function reports the field number as well as the window number to which the field belongs.

Note: Your application must allocate memory for each handle that it
      provides to Tools Plus by using the NewHandle routine.  Tools Plus
      does not automatically allocate this memory.  If your editing
      fields contain random characters, it is a sure sign that you have
      not allocated memory for your handle





Field Capacity
``````````````
  Fields are intended to handle small amounts of text, namely 255 characters or less.  They are not suitable for handling larger volumes of text.  Although an excess of thirty thousand characters can be typed or pasted in a single field (memory permitting), only the first 255 characters are significant.





Alignment of text in a field
````````````````````````````
  Each field can be either left aligned, right aligned, or centered.  It cannot, however, be fully justified (i.e. margin to margin).  Each field can have its own font, font size, and font styling.  Variations of font, size and style within a single field are not possible.





The Window’s Active Field
`````````````````````````
  Text editing can occur in only one field at a time (even if multiple applications are running concurrently).  The active field is the field in which the user is working.  The active field indicates it is active by containing either a flashing insertion point (called a “caret”), or several highlighted (selected) characters.

  A field is activated by using the ActivateField procedure.  When a field is first activated by your application, an insertion point can be placed at the beginning or at the end of the field’s text, or the field’s entire text can be selected.  In most cases, the field’s entire text is selected such as when the user tabs to another field.  When a window becomes inactive, the flashing insertion point disappears and selected text becomes deselected.  When the window is activated again, the insertion point or selection reappears.  A field can be deactivated by either calling the DeactivateField procedure, or by activating another field.

  Each window can have its own editing field that becomes the active editing field when its parent window is active.  This is called the window’s active field.  For example, field 3 could be active in the “add customer” window, and when the “add shipping address” window is active, field 8 could be active in that window.  This concept is simple as long as only one window is active at a time.

  When your application uses a tool bar and/or floating palettes, multiple windows are active simultaneously (the tool bar, all floating palettes, and the front most standard window).  Tools Plus manages the additional functionality required to make editing fields work on all windows in your application, including the tool bar and floating palettes.  It ensures that only one field is active at a time, and that it is the appropriate one.





Activating a Field
``````````````````
  On standard windows, your application uses ActivateField to specify the field that is active when its parent window is active.  This is usually done to specify the default field when the window is opened.  Your application also uses ActivateField to activate a new field when the user tabs to the next field or Shift-Tabs to the previous one.  The user can also start working in any field within an active window (subject to approval by your application) by clicking or double-clicking in the target field.

  Your application cannot, however, activate a field in a tool bar or floating palette -- the user must decide to work in a tool bar’s or palette’s field by clicking in the target field.  This ensures that Macintosh user interface guidelines are followed, and effectively prevents your application’s active field from arbitrarily jumping from one window to another.  Once the user starts working in a tool bar’s or floating palette’s editing field (by clicking in it), your application can activate other fields in the same window by using ActivateField.  The most common example of this is when the user tabs to the next field or Shift-Tabs to the previous one.

  Editing fields are fully integrated with windows.  As a result, Tools Plus prevents fields from being mysteriously activated or deactivated as windows are opened, closed, hidden, displayed, activated and deactivated.  The user’s interaction with editing fields is completely intuitive.





Editing Field Window
````````````````````
  The Editing Field Window is the one window in your application containing the active editing field (the field either has a flashing insertion point, or its selected text is highlighted).  Tools Plus automatically keeps track of which window contains your application’s active editing field.

  If your application does not use a tool bar or floating palettes, this window will likely be the active window (if it has an editing field).  If your application uses a tool bar and/or floating palettes, potentially any active window (tool bar, any floating palette, or the active standard window) can contain the active editing field.





The Field’s String & Edited Text
````````````````````````````````
  When a field is first created, a permanent association is made between the field at its text via a handle that points to the field’s string.  The field’s string is the text your application provides to a field for editing.

  When the field is first activated, a copy of its associated text (the field’s string) is made.  It is the copy that is edited within the field while the field’s original string is left untouched.  The copy is called the edited text.  The edited text can be inspected at any time by calling the GetFieldString procedure, which returns a copy of the edited text.  This is necessary to check the field’s edited text for errors prior to accepting it for storage as the field’s string.  The edited text can then be saved as the field’s string by calling the SaveFieldString procedure.

  When a field is deactivated, the field’s string is re-displayed, thereby replacing the edited text.  This is done in case your application deems that the edited text should not be saved as the field’s string.  If the edited text was saved as the field’s string, no apparent change is visible.

Note: Your application must allocate memory for each handle that it
      provides to Tools Plus by using the NewHandle or Tools Plus’s
      NewStrHandle routine.  Tools Plus does not automatically allocate
      this memory.  If your editing fields contain random characters, it
      is a sure sign that you have not allocated memory for your handle.





Fonts
`````
  When a field is created, the window’s current font, size and style settings (as set by the TextFont, TextSize, and TextFace procedures) are remembered by the field.  The window’s settings can then be changed without affecting the field.  Unlike regular Macintosh fields, interacting with these fields does not affect the window’s font settings (font, size, text-transfer mode, and style).





Length Limited Fields
`````````````````````
  In some applications, it may be necessary to limit the length of edited text to a specific number of characters.  This can be done by calling the FieldLengthLimit procedure with a value of “true.”  If a field has been “length limited,” it will not accept any characters that would make the length of the edited text exceed the size of the field’s string.  Instead, a beep is heard when the user types any keys.  This also applies when pasting text into a length-limited field.





Word Wrap
`````````
  Word wrap automatically occurs in fields.  When a word is too long to appear on the current line of a field, the entire word is moved to the next line and scrolling is performed (if necessary) to ensure that the insertion point is visible.  A word is defined as any series of characters excluding the space (ASCII character 32) and carriage return (ASCII character 13).

  If a field’s height is less than or equal to its font’s height (font height can be determined by calling the GetFontInfo procedure and adding Ascent + Descent + Leading ), and you disallow carriage return characters ($0D) in the field, the field is deemed to be a “single line field.”  Word wrap does not occur in single line fields.  Instead, the field’s text automatically scrolls to ensure that the selection always remains in view.





Clicking and Tabbing in fields
``````````````````````````````
  Clicking in an inactive field generates an event that is reported by PollSystem.  If a doClickField event is reported, your application would likely call GetFieldString to obtain a copy of the edited text and check the string for errors.  If an error is detected, display an appropriate alert box and ignore the doClickField event.  If no error is detected, call the SaveFieldString procedure to save the edited text as the field’s string, then call the ClickInField procedure that activates the required field and places the insertion point at the appropriate place.

  When a Tab or Shift-Tab key is reported by PollSystem in the form of a doKeyDown or doAutoKey event, your application would likely call the GetFieldString to obtain a copy of the edited text and to check the string for errors.  If an error is detected, display an appropriate alert box and ignore the doKeyDown or doAutoKey event.  If no error is detected, call the SaveFieldString procedure to save the edited text as the field’s string, then activate the appropriate field by calling ActivateField.  If Tab is pressed, activate the next field.  If Shift-Tab is pressed, activate the previous field.  The PollSystem function details key and mouse events.





Using Fields
````````````
  An inactive field cannot be edited by the user.  It must first be activated by clicking on the field or tabbing to it.  Note, however, that the contents of any field can be changed by your application by using the PasteInField routine.

  An active field contains either an insertion point (a flashing caret) or a selection (one or more highlighted characters).  A selection of characters is made by extending (dragging the mouse inside a field) away from the insertion point.  The insertion point’s position becomes a fixed “anchor,” and the selection is lengthened by moving the “head” away from the anchor, or shortened by moving it towards the anchor.  Fields automatically scroll to insure that the selection remains in view.

  When a field is active, all key-down and auto-key events are automatically intercepted and processed by the field.  Notable exceptions and features are listed below.  All events listed below are reported by PollSystem.

Note: Older keyboards, namely those found on the Macintosh 512KE and
      Macintosh Plus, have a “Backspace” key instead of a “Delete” key.
      However, it performs the same function.


  When the user types characters on the Mac’s keyboard and an editing field is active, Tools Plus automatically applies those characters to the active field (just as you would expect).  However, there are some keys on the keyboard that do not produce characters in the field.  Instead, they perform some function pertaining to the active field.  Below, is a list of those keys and the function they perform:

Command-(key)
`````````````
  Any Command-key sequence entered from the keyboard is first interpreted as a menu event.  If it matches a menu’s Command-key equivalent, the corresponding menu is highlighted and a doMenu event is generated.  Command-key equivalents for Undo, Cut, Copy, and Paste in the Edit menu are processed automatically without generating an event.  If the key does not match a menu’s Command-key equivalent, a doKeyDown or doAutoKey event is reported.  The edited text and selection are not changed.

Enter
`````
  If an enabled default button exists, the Enter key is interpreted as a doButton event for the default button.  Otherwise, a doKeyDown or doAutoKey event is reported.  The edited text and selection are not changed.

Return
``````
  If a window is open that contains an active editing field that accepts the Return key, the field executes a carriage return (move insertion point to the next line).  If the active field doesn’t accept a Return key, the keystroke is ignored.
  If a field is not active, and a default button exists on the active standard window, the Return key is interpreted as a doButton event for the default button.  Otherwise, a doKeyDown or doAutoKey event is reported.

Tab
```
  The Tab key generates a doKeyDown or doAutoKey event and must be processed by your application.  The edited text and selection are not changed.

Delete
``````
  If the Delete key is pressed at an insertion point, the character immediately to the left is erased without being placed on the clipboard.  Backspacing on a selection of characters erases the selection.

Delete Forward
``````````````
  If the Delete Forward key (available on extended keyboards) is pressed at an insertion point, the character immediately to the right is erased without being placed on the clipboard.  Deleting Forward on a selection of characters erases the selection.

Clear
`````
  Clear the field (i.e. erase all the characters) without placing them on the clipboard.  The clear key and the Clear item in the Edit menu perform the same function.

(Left arrow)
````````````
  When used at an insertion point, the caret is moved one character to the left.  When used at a selection range, the selection becomes an insertion point at the left side of the selection.  The edited text is not changed.

(Shift-left arrow)
``````````````````
  Lengthen or shorten the selection by one character (i.e. the range’s head is moved one character to the left).  The edited text is not changed.

(Option-left arrow)
```````````````````
  Move the insertion point one word to the left.  When used at an insertion point, the caret is moved leftward to the beginning of a word.  When used at a selection range, the selection becomes an insertion point and moves leftward to the beginning of a word.  The edited text is not changed.

(Option-Shift-left arrow)
`````````````````````````
  Lengthen or shorten the selection range by one word.  When used at an insertion point, a word is selected by moving leftward to the beginning of a word, then the selection is extended by moving the anchor rightward to the end of a single word.  When used at a selection range, the selection is first checked to ensure that it starts at the beginning of a word, and ends at the end of a word.  If this is the case, the selection range is lengthened or shortened by one word (i.e. the range’s head is moved one word to the left).  If the selection does not start at the beginning of a word and/or terminate at the end of a word, a word is selected by moving leftward to the beginning of a word, then the selection is extended by moving the anchor rightward to the end of a single word.  In all cases, the edited text is not changed.

(Right-arrow)
`````````````
  Move the insertion point one character to the right.  When used at an insertion point, the caret is moved one character to the right.  When used at a selection range, the selection becomes an insertion point at the right side of the selection.  The edited text is not changed.

(Shift-Right-arrow)
```````````````````
  Lengthen or shorten the selection by one character (i.e. the range’s head is moved one character to the right).  The edited text is not changed.

(Option-Right-arrow)
````````````````````
  Move the insertion point one word to the right.  When used at an insertion point, the caret is moved rightward to the beginning of a word.  When used at a selection range, the selection becomes an insertion point and is moved rightward to the beginning of a word.  The edited text is not changed.

(Option-Shift-Right-arrow)
``````````````````````````
  Lengthen or shorten the selection range by one word.  When used at an insertion point, a word is selected by moving rightward to the beginning of a word, then the selection is extended by moving the anchor leftward to the end of a single word.  When used at a selection range, the selection is first checked to ensure that it starts at the beginning of a word, and terminates at the end of a word.  If this is the case, the selection range is lengthened or shortened by one word (i.e. the range’s head is moved one word to the right).  If the selection does not begin at the beginning of a word and/or terminate at the end of a word, a word is selected by moving rightward to the beginning of a word, then the selection is extended by moving the anchor leftward to the end of a single word.  In all cases, the edited text is not changed.

(Up-arrow) or (Option-Up-arrow)
```````````````````````````````
  Move the insertion point up one line.  When used at an insertion point, the caret is moved up one line.  When used at a selection range, the selection becomes an insertion point at the left side of the selection.  Nothing happens if the insertion point is on the field’s first line.  The edited text is not changed.

(Shift-Up-arrow) or (Option-Shift-Up-arrow)
```````````````````````````````````````````
  Lengthen or shorten the selection by one line (i.e. the range’s head is moved up one line).  The edited text is not changed.

(Down-arrow) or (Option-Down arrow)
```````````````````````````````````
  Move the insertion point down one line.  When used at an insertion point, the caret moves down one line.  When used at a selection range, the selection becomes an insertion point at the right side of the selection.  Nothing happens if the insertion point is on the field’s last line.  The edited text is not changed.

(Shift-Down-arrow) or (Option-Shift-Down arrow)
```````````````````````````````````````````````
  Lengthen or shorten the selection by one line (i.e. the range’s head is moved down one line).  The edited text is not changed.

Clicking or Click/Drag
``````````````````````
  Clicking in an active field deselects the current selection and places an insertion point where the mouse was clicked.  If the mouse button is held down, the insertion point may be dragged to form a selection range.  The field’s text scrolls automatically to keep the selection in view.
  If a click occurs in an inactive field, a doClickField event is reported.  Your application should then respond by validating the active field’s text (GetFieldString procedure), then saving the field’s edited text by using the SaveFieldString procedure.  Then, by calling the ClickInField procedure, the click is processed as previously described.

Double-Clicking or Double Click/Drag
````````````````````````````````````
  Double-clicking in an active field deselects the current selection and selects the word that was clicked.  If the mouse button is held down, the selection range may be dragged to extend or shorten the range by one word.  The field’s text scrolls automatically to keep the selection in view.
  If a double-click occurs in an inactive field, a doClickField event is generated.  Your application should then respond by validating the active field’s text (GetFieldString procedure), then saving the field’s edited text by using the SaveFieldString procedure.  Then, by calling the ClickInField procedure, the double-click is processed as previously described.





Mac 512KE and Mac Plus keyboard with numeric pad
````````````````````````````````````````````````
  In order to provide the Shift-Arrow combinations as previously described, Tools Plus must discern an Arrow key from a Shift-Arrow key.  This causes a slight problem on Macintosh 512KE and Macintosh Plus keyboards.  Shift-(left arrow), for example, produces the same key code as the “+” on the numeric pad.  A problem arises when Tools Plus cannot discern between a Shift-(left arrow) and a “+” key on the numeric pad.

  It is for this reason that the =, /, *, and + keys on the numeric pad are treated as Shift-(down arrow), Shift-(up arrow), Shift-(right arrow), and Shift-(left arrow) respectively.  This occurs only in an active field on a Macintosh 512KE and Macintosh Plus.





The Edit Menu
`````````````
  If a second menu exists, it must be called “Edit” and must contain “Undo”, “Cut”, “Copy”, “Paste” and “Clear” as the first five items in the listed order.  A dividing line must exist between “Undo” and “Cut”.  See the chapter on Menus for more details.

  When a field is active in a modeless window, the Edit menu’s “Undo”, “Cut”, “Copy”, “Paste”, and “Clear” items automatically affect the active field in the following manner:

Undo
````
  Undo is disabled when a field is activated or deactivated.  It is enabled and changed to “Undo Cut” if the Cut command is selected, if a selection range is Deleted, or if a field is Cleared by using the Clear key or Clear menu items.  Undo is changed to “Undo Copy” and “Undo Paste” when the respective menus are selected, and changed to “Undo Typing” when keys are typed or the Delete key is used at an insertion point.
  Selecting “Undo task” performs all the necessary operations that are required to undo the previous operation, and changes the item to “Redo task.”  Selecting “Redo task” restores the field to a state prior to the “Undo task” selection.  Undoing and Redoing also remembers insertion point positions and selection ranges.

Cut
```
  Cut deletes the selected text from the field and places it on the Clipboard.  This item is disabled when a field is deactivated or when an insertion point exists in an active field (i.e. a selection range has not been made).

Copy
````
  Copy takes a copy of the selected text and places it on the Clipboard without changing the field.  Copy is disabled when a field is deactivated or when an insertion point exists in an active field (i.e. a selection range has not been made).

Paste
`````
  At an insertion point, Paste inserts a copy of the Clipboard’s text.  At a selection range, Paste replaces the selected characters with the Clipboard’s text.  The Clipboard’s contents are not changed.
  In a length limited field, the Clipboard’s text is pasted a character at a time (although very quickly) until all the Clipboard’s text has been pasted, or the field is full (whichever comes first).
  Paste does not paste Carriage Returns into fields where they are disallowed.
  Paste is disabled when a field is deactivated or when no text exists on the Clipboard.  Paste is also disabled if a field has been length limited and the insertion point is in a field that has reached its limit of characters (i.e. a full field).

Clear
`````
  Clear is disabled when a field is deactivated, or if an active field contains no text (a string length of 0).  Clear deletes all the text in the field (i.e. erase all the characters) without placing them on the clipboard.  The clear key and the Clear item in the Edit menu perform the same function.





Handling Fields
```````````````
  Once a field is activated, Tools Plus performs all the editing required within the field.  When a window in inactive, Tools Plus deselects the text in the active field on that window and hides the insertion point.  When the window is activated again, the active field regains its original state.  The PollSystem function, which is used to constantly inquire about any requests the system may have, also processes keystrokes for fields, and maintains the enabled/disabled status for the Edit menu’s Undo, Cut, Copy, Paste, and Clear items.

  The active field is automatically affected if the user selects the Edit Menu’s Undo, Cut, Copy, Paste, or Clear command.  Command-key equivalents for these items have the same effect.

  Many types of events may indicate that the user has completed using the field.  For example, a doKeyDown event may report that Tab or Return was pressed, indicating the user wishes to advance to the next field.  The doClickField event may indicate that the user has clicked on an inactive field, or the doMenu event may indicate that the user wants to quit your application.  In these cases,e the active field’s edited text before accepting it as the field’s string.  A copy of the field’s edited text can be obtained by GetFieldString.  If your application determines that the edited text is invalid, display an appropriate alert box and ignore the event.  If no error is detected, call the SaveFieldString procedure to save the edited text as the field’s string, then process the event.

If your application needs to monitor changes as they occur in an editing field, it can do so by responding to the doChgInField event. An example of this is disabling a “save” button when a field is empty.

See the PollSystem function for details.





Special Handling of Fields
```````````````````````````
  Some applications may find it necessary to reposition a field.  An example of this occurs in an application that has a matrix of fields aligned as cells: 3 columns across and 10 lines down.  If your application needs to “scroll” this block of fields, it is necessary to change the position of existing fields.  This can be done by using the OffsetField procedure.

  Another unusual circumstance occurs if your application needs to paste text into a field under your application’s control.  For example, your application may choose to insert a commonly used word or phrase into a field when the user selects a menu item or a specific command key.  The PasteIntoField procedure allows text to be pasted directly into a field.

If your application sets other user interface elements depending on a field’s contents (i.e., disabling a “Save” button if a field is empty), then you can use the doChgInField event which is reported whenever the active field’s contents are changed.  See the PollSystem function for details.